home *** CD-ROM | disk | FTP | other *** search
/ Nebula 1 / Nebula One.iso / Internet / WWW / Perl_WWW_Utilities / total / textcounter / README < prev   
Encoding:
Text File  |  1996-03-14  |  10.3 KB  |  216 lines
  1. ##############################################################################
  2. # WWWCount Text Version (Requires Server Side Includes) Version 1.0         #
  3. # Created by Matt Wright    mattw@worldwidemart.com                 #
  4. # Created on: 3/14/96        Last Modified on: 3/14/96                #
  5. # Scripts Found at:             http://www.worldwidemart.com/scripts/        #
  6. ##############################################################################
  7. # If you run into any problems while trying to configure this script, help  #
  8. # is available.  The steps you should take to get the fastest results, are:  #
  9. #       1) Read this file thoroughly                                         #
  10. #       2) Consult the Matt's Script Archive Frequently Asked Questions:     #
  11. #               http://www.worldwidemart.com/scripts/faq/                    #
  12. #       3) If you are still having difficulty installing this script, send   #
  13. #          e-mail to: scripts-help@tahoenet.com                              #
  14. #          Include any error messages you are receiving and as much detail   #
  15. #          as you can so we can spot your problem.  Also include the variable#
  16. #          configuration block that is located at the top of the script.     #
  17. #                                                                            #
  18. # Hopefully we will be able to help you solve your problems.  Thank you.     #
  19. ##############################################################################
  20. # COPYRIGHT NOTICE                                                           #
  21. # Copyright 1996 Matthew M. Wright  All Rights Reserved.                     #
  22. #                                                                            #
  23. # WWWCount may be used and modified free of charge by anyone so long as this #
  24. # copyright notice and the comments above remain intact.  By using this      #
  25. # code you agree to indemnify Matthew M. Wright from any liability that      # 
  26. # might arise from it's use.                                                 #
  27. #                                                                            #
  28. # Selling the code for this program without prior written consent is         #
  29. # expressly forbidden.  In other words, please ask first before you try and  #
  30. # make money off of my program.                                              #
  31. ##############################################################################
  32.  
  33. WWWCount Text Version 1.0 is a simple program which allows you to include 
  34. a text counter on any page.  You can also include the date since it began 
  35. counting, a link to a help page, etc...  This program was designed for 
  36. anyone to use, from a user who just wants a text counter on his or her 
  37. home page to a system administrator who wants to make it easy for anyone 
  38. on their server to use the count program.  Multiple counters can be set 
  39. up, with the need for only one script to manage them all.  You can 
  40. specify what hosts are allowed to access this program, and can even allow 
  41. certain directories or exclude certain directories from being able to use 
  42. this script.  Details on how to install and use this script are available 
  43. below.
  44.  
  45. This package should have come with 2 files:
  46.     1) README     - This file.  Installation Instructions, 
  47.               Disclaimer, Copyright
  48.     2) WWWCount.cgi - The CGI/Perl program which does all of the work.
  49.  
  50. Installation:
  51. =============
  52.  
  53. WWWCount.cgi
  54. ------------
  55.  
  56. The first thing you will need to do when you get ahold of this script is 
  57. make sure that the first line of the script correctly points to the Perl 
  58. executable on your system.  If you don't know where this is for sure, use 
  59. the command:
  60.  
  61. which perl
  62. or
  63. whereis perl
  64.  
  65. from your Unix shell.
  66.  
  67. There are also several Variables and Options you will need to configure.  
  68. The instructions below provide examples and instructions of how to do so.
  69.  
  70. VARIABLE CONFIGURATION:
  71.     $data_dir = "/path/to/a/data/directory/";
  72.         The $data_dir variable should specify the path to the 
  73.         directory under which all of th data files will be stored.
  74.         This path must end with a '/' and it NEEDS to be writable by 
  75.         your web server.  This means that you most likely will need 
  76.         to chmod this directory 777.  You can do this by executing:
  77.  
  78.             chmod 777 /path/to/a/data/directory/
  79.  
  80.         It is suggested that you make this directory a brand new 
  81.         directory for the sole purpose of holding the data files.  A 
  82.         new data file will be created for each page you add your text
  83.         counter to.  You may think that this is not the best way to 
  84.         do this, but it is not all bad, and is beneficial in some 
  85.         ways:
  86.  
  87.             1) If you use this system wide, it is likely that 
  88.                many pages will load at the same time, meaning 
  89.                 this script would have to try and edit the main 
  90.                file if it was all included in one database.  
  91.                This file can lead to slow downs (if I locked the
  92.                file each time it was called) or it could lead to 
  93.                mangled data if I didn't.  That is one reason I 
  94.                chose to use separate files.
  95.             2) The files created for the data are EXTREMELY 
  96.                small, taking up between 15 and 30 bytes (yes, 
  97.                you heard correctly, bytes).
  98.             3) Access time is faster as I know exactly what 
  99.                file to open, rather than flipping through lines 
  100.                of a database if it was all in one file.
  101.             (BTW, this explanation was more for people who 
  102.             may have questioned why I chose to do it this way.  
  103.             Most of you could care less about these last 3 points)
  104.               :-)
  105.  
  106.     @valid_referer = ("your.host.com","your.ip.address");
  107.         The @valid_referer variable makes sure all requests are 
  108.         coming from the machines listed in this array.  That does 
  109.         not mean only people at these addresses will see the counter.
  110.           What it does mean is that only WWW pages that are on these 
  111.         servers will be able to use this program.  Keeps out people 
  112.         who like to bum off of other's servers.
  113.  
  114.     @valid_uri = ("/");
  115.         The @valid_uri array allows you to allow this script to 
  116.         be used only under a certain directory of your server.  Say 
  117.         your username is fred and you are on a server called 
  118.         host.com, therefore all of your pages reside under: 
  119.         http://www.host.com/~fred/.  You only want those pages under
  120.         that directory to be able to use this program, so you set the 
  121.         @valid_uri variable to ("/~fred"); or you can allow you and 
  122.         your friend joe to use it by setting the @valid_uri variable
  123.         to: ("/~fred","/~joe");  Or if you are a sysadmin who wants 
  124.         to allow everyone to use this script, simply set this array 
  125.         to ("/"); as I have shown above.
  126.  
  127.     @invalid_uri = ("");
  128.         Most likely you will just comment this line out if you do 
  129.         not wish to block access to a certain part of your server.
  130.         But take the example of fred above.  He decides to be real 
  131.         cool and open this program up to anyone on the server by 
  132.         setting @valid_uri = ("/");  His arch enemy bob is also on 
  133.         the server though, and fred despises him so much that he 
  134.         wants to block access to this guy, cause bob is such a jerk.
  135.         So fred sets his @invalid_uri = ("/~bob"); and bob can't use 
  136.         his counter. MU HA HA HA.  I'm sure there are other cool uses
  137.         for this too.  Like if you sell virtual domains and want to 
  138.         charge people before they can use your counter script, you 
  139.         put their URI in here until they pay or something.  I dunno. 
  140.         The story was fun to write, and that's all that matters. :-)
  141.  
  142. OPTION SETTINGS:
  143.     $show_link = "http://www.worldwidemart.com/scripts/";
  144.         If you put a URL into this option, then the actual number 
  145.         returned by the WWWCount script will be linked to this 
  146.         URL.  This is useful if you want to link to my site 
  147.         (PLEASE?!) or link to a help page explaining how the user 
  148.         on your system can set up their own text counter.  or if 
  149.         you just want to have a pointless link on your number.  
  150.         Setting this to a null value like "" or 0 will take out the
  151.         link.
  152.  
  153.     $auto_create = "1";
  154.         Suggested value here is 1, or else you will have to 
  155.         create data files by hand.  This allows users who reside 
  156.         under the @valid_uri and @valid_referer arrays to create a
  157.         new counter for their page simply by putting the Server 
  158.         Side Include reference into their page.  Otherwise the 
  159.         maintainer will have to create a data file which looks like:
  160.  
  161.             January 1, 2000||0
  162.  
  163.         Obviously putting the correct date into the script and 
  164.         changing 0 to whatever you want to start the number at.  
  165.         This file MUST be writable by the web server meaning you 
  166.         need to chmod it 777.  This means other users on your 
  167.         system can write to it too, which is another reason to allow 
  168.         auto-create.  Auto-Create will leave it chmoded so only the 
  169.         web server can write to it.
  170.  
  171.     $show_date = "1";
  172.         If this variable is on, then the date on which you began 
  173.         the count will appear with your actual count number.  It 
  174.         will look like: 
  175.  
  176.             [Count] hits since [Date]
  177.  
  178.         If this is turned off, you allow users more control over 
  179.         their text and it will simply print:
  180.  
  181.             [Count]
  182.  
  183.         The user can then supply the date if they wish.
  184.  
  185. ______________________________________________________________________________
  186.  
  187. HOW TO CALL THIS SCRIPT FROM YOUR PAGE?
  188.  
  189. Calling this program is really very simple.  As I have mentioned before, 
  190. you will need Server Side Includes turned on on your server before you 
  191. can use this program.  Talk to your system administrator or visit my 
  192. Frequently Asked Questions section for more information on server side 
  193. includes.  If you know they are turned on, or want to try and find out, 
  194. put the following code into your HTML document:
  195.  
  196. <!--#exec cgi="/virtual/path/to/counter.pl"-->
  197.  
  198. So, if I have my counter.pl (or counter.cgi if I have to rename it for 
  199. my server) program located at 
  200. http://www.worldwidemart.com/scripts/demos/textcounter/counter.pl, then I 
  201. would put the following into any HTML document a wanted a count to appear in:
  202.  
  203. <!--#exec cgi="/scripts/demos/textcounter/counter.pl"-->
  204.  
  205. _____________________________________________________________________________
  206.  
  207. Well, that covers all of the options and variables, and I explained these 
  208. in such detail that hopefully I won't get swamped by help mail for this 
  209. script. :-D (Yah right!)  But please, before you ask for help, follow the 
  210. steps at the top of this document.  You probably won't get an answer from 
  211. myself or the help staff if your answer is in the Frequently Asked 
  212. Questions at my site.
  213. _____________________________________________________________________________
  214. Matt Wright - mattw@worldwidemart.com - http://www.worldwidemart.com/scripts/
  215.  
  216.